Input-Related Functions

The following functions are the BView non-hook function related to user input and input processing. Note that the most important input-related functions are hook functions; see the Hook Functions section.

BeginRectTracking() , EndRectTracking()

void BeginRectTracking(BRect rect, uint32 how = B_TRACK_WHOLE_RECT) void EndRectTracking(void)

These functions instruct the Application Server to display a rectangular outline that will track the movement of the cursor. BeginRectTracking() puts the rectangle on-screen and initiates tracking; EndRectTracking() terminates tracking and removes the rectangle. The initial rectangle, rect, is specified in the BView's coordinate system.

This function supports two kinds of tracking, depending on the constant passed as the how argument:

B_TRACK_WHOLE_RECT	The whole rectangle moves with the cursor. Its position changes, but its size remains fixed.
B_TRACK_RECT_CORNER	The left top corner of the rectangle remains fixed within the view while its right and bottom edges move with the cursor.

Tracking is typically initiated from within a BView's MouseDown() function and is terminated in MouseUp()

DragMessage()

void DragMessage(BMessage *message, BBitmap *image, BPoint point,       BHandler *replyTarget = NULL) void DragMessage(BMessage *message, BRect rect,       BHandler *replyTarget = NULL) void DragMessage(BMessage *message, BBitmap *image, drawing_mode dragMode,       BPoint offset, BHandler *replyTarget = NULL)

Initiates a drag-and-drop session.

message, is a BMessage object that bundles the information that will be dragged and dropped on the destination view. The caller retains responsibility for this object and can delete it after DragMessage() return (the BView makes a copy of the message).

image, is a bitmap that the user can drag. The bitmap is automatically freed when the message is dropped.

1 bit-per-pixel bitmaps aren't supported; you should avoid using them.

point locates the hotspot within image (in the bitmap's coordinate system). This is the point that's aligned with the location passed to MouseDown() or returned by GetMouse().

rect defines the dimensions of an outline rectangle that you can instead of a bitmap. The rectangle is stated in the BView's coordinate system.

replyTarget, names the object that you want to handle a message that might be sent in reply to the dragged message. If replyTarget is NULL, as it is by default, any reply that's received will be directed to the BView object that initiated the drag-and-drop session.

dragMode defines the drawing_mode which will be used to draw image as the image is dragged around. This is provided primarily so that transparent or partially transparent images can be dragged around (using the B_OP_ALPHA drawing mode).

This function works only for BView objects that are attached to a window.

EndRectTracking()  see BeginRectTracking()

GetMouse()

void GetMouse(BPoint *cursor, uint32 *buttons, bool checkQueue = true)

Provides the location of the cursor and the state of the mouse buttons. The position of the cursor is recorded in the variable referred to by cursor; it's provided in the BView's own coordinates. A bit is set in the variable referred to by buttons for each mouse button that's down. This mask may be 0 (if no buttons are down) or it may contain one or more of the following constants:

B_PRIMARY_MOUSE_BUTTO N

B_SECONDARY_MOUSE_BU TTON

B_TERTIARY_MOUSE_BUTT ON

The cursor doesn't have to be located within the view for this function to work; it can be anywhere on-screen. However, the BView must be attached to a window.

If the checkQueue flag is set to false, GetMouse() provides information about the current state of the mouse buttons and the current location of the cursor.

If checkQueue is true, as it is by default, this function first looks in the message queue for any pending reports of mouse-moved or mouse-up events. If it finds any, it takes the one that has been in the queue the longest (the oldest message), removes it from the queue, and reports the cursor location and button states that were recorded in the message. Each GetMouse() call removes another message from the queue. If the queue doesn't hold any B_MOUSE_MOVED or B_MOUSE_UP messages, GetMouse() reports the current state of the mouse and cursor, just as if checkQueue were false.

If checkQueue is true, and the view's parent window has pending update events, GetMouse() causes those update events to be processed.

You shouldn't use this function to track the mouse; implement the MouseMoved() function instead.

See also: modifiers()

MakeFocus()

virtual void MakeFocus(bool focused = true)

Makes the BView the current focus view for its window (if the focused flag is true), or causes it to give up that status (if focused is false). The focus view is the view that displays the current selection and is expected to handle reports of key-down events when the window is the active window. There can be no more than one focus view per window at a time.

When called to make a BView the focus view, this function invokes MakeFocus() for the previous focus view, passing it an argument of false. It's thus called twice—once for the new and once for the old focus view.

Calling MakeFocus() is the only way to make a view the focus view; the focus doesn't automatically change on mouse-down events. BViews that can display the current selection (including an insertion point) or that can accept pasted data should call MakeFocus() in their MouseDown() functions.

A derived class can override MakeFocus() to add code that takes note of the change in status. For example, a BView that displays selectable data may want to highlight the current selection when it becomes the focus view, and remove the highlighting when it's no longer the focus view. A BView that participates in the keyboard navigation system should visually indicate that it can be operated from the keyboard when it becomes the focus view, and remove that indication when the user navigates to another view and it's notified that it's no longer the focus view.

If the BView isn't attached to a window, this function has no effect.

See also: BWindow::CurrentFocus(), IsFocus()

MessageReceived()

virtual void MessageReceived(BMessage *message)

Augments the BHandler version of MessageReceived() to handle scripting messages for the BView.

See also: BHandler::MessageReceived()

ScrollBar()

BScrollBar *ScrollBar(orientation posture) const

Returns a BScrollBar object that scrolls the BView (that has the BView as its target). The requested scroll bar has the posture orientation—B_VERTICAL or B_HORIZONTAL. If the BView isn't the target of a scroll bar with the specified orientation, this function returns NULL.

See also: ScrollBar::SetTarget()

ScrollBy() , ScrollTo()

void ScrollBy(float horizontal, float vertical) virtual void ScrollTo(BPoint point) inline void ScrollTo(float x, float y)

These functions scroll the contents of the view, provided that the BView is attached to a window.

ScrollBy() adds horizontal to the left and right components of the BView's bounds rectangle, and vertical to the top and bottom components. This serves to shift the display horizontal coordinate units to the left and vertical units upward. If horizontal and vertical are negative, the display shifts in the opposite direction.

ScrollTo() shifts the contents of the view as much as necessary to put point—or (x, y)—at the upper left corner of its bounds rectangle. The point is specified in the BView's coordinate system.

Anything in the view that was visible before scrolling and also visible afterwards is automatically redisplayed at its new location. The remainder of the view is invalidated, so the BView's Draw() function will be called to fill in those parts of the display that were previously invisible. The update rectangle passed to Draw() will be the smallest possible rectangle that encloses just these new areas. If the view is scrolled in only one direction, the update rectangle will be exactly the area that needs to be drawn.

If the BView is the target of scroll bars, ScrollBy() and ScrollTo() notify the BScrollBar objects of the change in the display so they can update themselves to match. If the contents were scrolled horizontally, they call the horizontal BScrollBar's SetValue() function and pass it the new value of the left side of the bounds rectangle. If they were scrolled vertically, they call SetValue() for the vertical BScrollBar and pass it the new value of the top of the bounds rectangle.

The inline version of ScrollTo() works by creating a BPoint object and passing it to the version that's declared virtual. Therefore, if you want to override either function, you should override the virtual version. (However, due to the peculiarities of C++, overriding any version of an overloaded function hides all versions of the function. For continued access to the nonvirtual version without explicitly specifying the "BView::" prefix, simply copy the inline code from interface/View.h into the derived class.)

SetEventMask() , SetMouseEventMask() , EventMask()

status_t SetEventMask(uint32 events, uint32 options=0) status_t SetMouseEventMask(uint32 events, uint32 options=0) uint32 EventMask(void)

SetEventMask() lets you extend the scope of the mouse and keyboard events that the view can receive. If events include B_POINTER_EVENTS, the view will receive mouse events (aka pointer events) even when the mouse isn't over the view; if it includes B_KEYBOARD_EVENTS, the view will receive keyboard events even if the view isn't in focus. (We'll look at the options argument below).

SetMouseEventMask() does the same thing as SetEventMask(), except (1) it can only be called from within an implementation of MouseDown(), and (2) the new events value—which is added to the current event mask—is only in effect until (and including) the following mouse up event. When the mouse is released, the view's previous event mask (as set through SetEventMask()) is re-established.

The option arguments lets you request other event-handling modifications (note that SetEventMask() only accepts the first of these options; SetMouseEventMask() accepts all three):

• B_NO_POINTER_HISTORY. This tells the App Server to only send the most recent pointer moved (i.e. mouse moved) event to your view (all "old" events are thrown away). You use this option if your MouseMoved() implementation is too heavy to keep up with the mouse moved messages that are pouring in. Of course, your view may lose some mouse movement granularity, but that's the price you pay to stay in synch with the user.

• B_SUSPEND_VIEW_FOCUS (SetMouseEventMask() only). Events that are normally sent to the focus view are suppressed. In practice, this means that while the mouse is held down, the keyboard is turned off. Note that the view that's processing the MouseDown() messages doesn't have to be the focus view to suppress focused messages.

• B_LOCK_WINDOW_FOCUS (SetMouseEventMask() only). Prevents the view's window from losing focused status while the mouse is down, even if the mouse leaves the window's bounds.

To ask for an option without changing the event mask (or mouse event mask), pass 0 as the events argument.

Both SetEventMask() and SetMouseEventMask() require that the view be attached to a window; they have no effect if the view isn't already attached.

EventMask() returns the view's event mask as set through SetEventMask(). It doesn't consider the mask set in SetMouseEventMask().